home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 November / CPNL0711.ISO / admin / secure / Tor - Privoxy - Vidalia.exe / Tor / Documents / dir-spec.txt < prev    next >
Text File  |  2007-08-30  |  68KB  |  1,580 lines
  1. $Id: dir-spec.txt 11268 2007-08-24 14:41:06Z nickm $
  2.  
  3.                       Tor directory protocol, version 3
  4.  
  5. 0. Scope and preliminaries
  6.  
  7.    This directory protocol is used by Tor version 0.2.0.x-alpha and later.
  8.    See dir-spec-v1.txt for information on the protocol used up to the
  9.    0.1.0.x series, and dir-spec-v2.txt for information on the protocol
  10.    used by the 0.1.1.x and 0.1.2.x series.
  11.  
  12.    Caches and authorities must still support older versions of the
  13.    directory protocols, until the versions of Tor that require them are
  14.    finally out of commission.  See Section XXXX on backward compatibility.
  15.  
  16.    This document merges and supersedes the following proposals:
  17.  
  18.        101  Voting on the Tor Directory System
  19.        103  Splitting identity key from regularly used signing key
  20.        104  Long and Short Router Descriptors
  21.  
  22.    AS OF 14 JUNE 2007, THIS SPECIFICATION HAS NOT YET BEEN COMPLETELY
  23.    IMPLEMENTED, OR COMPLETELY COMPLETED.
  24.  
  25.    XXX when to download certificates.
  26.    XXX timeline
  27.    XXX fill in XXXXs
  28.  
  29. 0.1. History
  30.  
  31.    The earliest versions of Onion Routing shipped with a list of known
  32.    routers and their keys.  When the set of routers changed, users needed to
  33.    fetch a new list.
  34.  
  35.    The Version 1 Directory protocol
  36.    --------------------------------
  37.  
  38.    Early versions of Tor (0.0.2) introduced "Directory authorities": servers
  39.    that served signed "directory" documents containing a list of signed
  40.    "router descriptors", along with short summary of the status of each
  41.    router.  Thus, clients could get up-to-date information on the state of
  42.    the network automatically, and be certain that the list they were getting
  43.    was attested by a trusted directory authority.
  44.  
  45.    Later versions (0.0.8) added directory caches, which download
  46.    directories from the authorities and serve them to clients.  Non-caches
  47.    fetch from the caches in preference to fetching from the authorities, thus
  48.    distributing bandwidth requirements.
  49.  
  50.    Also added during the version 1 directory protocol were "router status"
  51.    documents: short documents that listed only the up/down status of the
  52.    routers on the network, rather than a complete list of all the
  53.    descriptors.  Clients and caches would fetch these documents far more
  54.    frequently than they would fetch full directories.
  55.  
  56.    The Version 2 Directory Protocol
  57.    --------------------------------
  58.  
  59.    During the Tor 0.1.1.x series, Tor revised its handling of directory
  60.    documents in order to address two major problems:
  61.  
  62.       * Directories had grown quite large (over 1MB), and most directory
  63.         downloads consisted mainly of router descriptors that clients
  64.         already had.
  65.  
  66.       * Every directory authorities was a trust bottleneck: if a single
  67.         directory authority lied, it could make clients believe for a time
  68.         an arbitrarily distorted view of the Tor network.  (Clients
  69.         trusted the most recent signed document they downloaded.) Thus,
  70.         adding more authorities would make the system less secure, not
  71.         more.
  72.  
  73.    To address these, we extended the directory protocol so that
  74.    authorities now published signed "network status" documents.  Each
  75.    network status listed, for every router in the network: a hash of its
  76.    identity key, a hash of its most recent descriptor, and a summary of
  77.    what the authority believed about its status.  Clients would download
  78.    the authorities' network status documents in turn, and believe
  79.    statements about routers iff they were attested to by more than half of
  80.    the authorities.
  81.  
  82.    Instead of downloading all router descriptors at once, clients
  83.    downloaded only the descriptors that they did not have.  Descriptors
  84.    were indexed by their digests, in order to prevent malicious caches
  85.    from giving different versions of a router descriptor to different
  86.    clients.
  87.  
  88.    Routers began working harder to upload new descriptors only when their
  89.    contents were substantially changed.
  90.  
  91.  
  92. 0.2. Goals of the version 3 protocol
  93.  
  94.    Version 3 of the Tor directory protocol tries to solve the following
  95.    issues:
  96.  
  97.       * A great deal of bandwidth used to transmit router descriptors was
  98.         used by two fields that are not actually used by Tor routers
  99.         (namely read-history and write-history).  We save about 60% by
  100.         moving them into a separate document that most clients do not
  101.         fetch or use.
  102.  
  103.       * It was possible under certain perverse circumstances for clients
  104.         to download an unusual set of network status documents, thus
  105.         partitioning themselves from clients who have a more recent and/or
  106.         typical set of documents.  Even under the best of circumstances,
  107.         clients were sensitive to the ages of the network status documents
  108.         they downloaded.  Therefore, instead of having the clients
  109.         correlate multiple network status documents, we have the
  110.         authorities collectively vote on a single consensus network status
  111.         document.
  112.  
  113.       * The most sensitive data in the entire network (the identity keys
  114.         of the directory authorities) needed to be stored unencrypted so
  115.         that the authorities can sign network-status documents on the fly.
  116.         Now, the authorities' identity keys are stored offline, and used
  117.         to certify medium-term signing keys that can be rotated.
  118.  
  119. 0.3. Some Remaining questions
  120.  
  121.    Things we could solve on a v3 timeframe:
  122.  
  123.      The SHA-1 hash is showing its age.  We should do something about our
  124.      dependency on it.  We could probably future-proof ourselves here in
  125.      this revision, at least so far as documents from the authorities are
  126.      concerned.
  127.  
  128.      Too many things about the authorities are hardcoded by IP.
  129.  
  130.      Perhaps we should start accepting longer identity keys for routers
  131.      too.
  132.  
  133.    Things to solve eventually:
  134.  
  135.      Requiring every client to know about every router won't scale forever.
  136.  
  137.      Requiring every directory cache to know every router won't scale
  138.      forever.
  139.  
  140.  
  141. 1. Outline
  142.  
  143.    There is a small set (say, around 5-10) of semi-trusted directory
  144.    authorities.  A default list of authorities is shipped with the Tor
  145.    software.  Users can change this list, but are encouraged not to do so,
  146.    in order to avoid partitioning attacks.
  147.  
  148.    Every authority has a very-secret, long-term "Authority Identity Key".
  149.    This is stored encrypted and/or offline, and is used to sign "key
  150.    certificate" documents.  Every key certificate contains a medium-term
  151.    (3-12 months) "authority signing key", that is used by the authority to
  152.    sign other directory information.  (Note that the authority identity
  153.    key is distinct from the router identity key that the authority uses
  154.    in its role as an ordinary router.)
  155.  
  156.    Routers periodically upload signed "routers descriptors" to the
  157.    directory authorities describing their keys, capabilities, and other
  158.    information.  Routers may also upload signed "extra info documents"
  159.    containing information that is not required for the Tor protocol.
  160.    Directory authorities serve router descriptors indexed by router
  161.    identity, or by hash of the descriptor.
  162.  
  163.    Routers may act as directory caches to reduce load on the directory
  164.    authorities.  They announce this in their descriptors.
  165.  
  166.    Periodically, each directory authority periodically generates a view of
  167.    the current descriptors and status for known routers.  They send a
  168.    signed summary of this view (a "status vote") to the other
  169.    authorities.  The authorities compute the result of this vote, and sign
  170.    a "consensus status" document containing the result of the vote.
  171.  
  172.    Directory caches download, cache, and re-serve consensus documents.
  173.  
  174.    Clients, directory caches, and directory authorities all use consensus
  175.    documents to find out when their list of routers is out-of-date.
  176.    (Directory authorities also use vote statuses.) If it is, they download
  177.    any missing router descriptors.  Clients download missing descriptors
  178.    from caches; caches and authorities download from authorities.
  179.    Descriptors are downloaded by the hash of the descriptor, not by the
  180.    server's identity key: this prevents servers from attacking clients by
  181.    giving them descriptors nobody else uses.
  182.  
  183.    All directory information is uploaded and downloaded with HTTP.
  184.  
  185.    [Authorities also generate and caches also cache documents produced and
  186.    used by earlier versions of this protocol; see section XXX for notes.]
  187.  
  188. 1.1. What's different from version 2?
  189.  
  190.    Clients used to download a multiple network status documents,
  191.    corresponding roughly to "status votes" above.  They would compute the
  192.    result of the vote on the client side.
  193.  
  194.    Authorities used to sign documents using the same private keys they used
  195.    for their roles as routers.  This forced them to keep these extremely
  196.    sensitive keys in memory unencrypted.
  197.  
  198.    All of the information in extra-info documents used to be kept in the
  199.    main descriptors.
  200.  
  201. 1.2. Document meta-format
  202.  
  203.   Router descriptors, directories, and running-routers documents all obey the
  204.   following lightweight extensible information format.
  205.  
  206.   The highest level object is a Document, which consists of one or more
  207.   Items.  Every Item begins with a KeywordLine, followed by zero or more
  208.   Objects. A KeywordLine begins with a Keyword, optionally followed by
  209.   whitespace and more non-newline characters, and ends with a newline.  A
  210.   Keyword is a sequence of one or more characters in the set [A-Za-z0-9-].
  211.   An Object is a block of encoded data in pseudo-Open-PGP-style
  212.   armor. (cf. RFC 2440)
  213.  
  214.   More formally:
  215.  
  216.     Document ::= (Item | NL)+
  217.     Item ::= KeywordLine Object*
  218.     KeywordLine ::= Keyword NL | Keyword WS ArgumentsChar+ NL
  219.     Keyword = KeywordChar+
  220.     KeywordChar ::= 'A' ... 'Z' | 'a' ... 'z' | '0' ... '9' | '-'
  221.     ArgumentChar ::= any printing ASCII character except NL.
  222.     WS = (SP | TAB)+
  223.     Object ::= BeginLine Base-64-encoded-data EndLine
  224.     BeginLine ::= "-----BEGIN " Keyword "-----" NL
  225.     EndLine ::= "-----END " Keyword "-----" NL
  226.  
  227.     The BeginLine and EndLine of an Object must use the same keyword.
  228.  
  229.   When interpreting a Document, software MUST ignore any KeywordLine that
  230.   starts with a keyword it doesn't recognize; future implementations MUST NOT
  231.   require current clients to understand any KeywordLine not currently
  232.   described.
  233.  
  234.   The "opt" keyword was used until Tor 0.1.2.5-alpha for non-critical future
  235.   extensions.  All implementations MUST ignore any item of the form "opt
  236.   keyword ....." when they would not recognize "keyword ....."; and MUST
  237.   treat "opt keyword ....."  as synonymous with "keyword ......" when keyword
  238.   is recognized.
  239.  
  240.   Implementations before 0.1.2.5-alpha rejected any document with a
  241.   KeywordLine that started with a keyword that they didn't recognize.
  242.   When generating documents that need to be read by older versions of Tor,
  243.   implementations MUST prefix items not recognized by older versions of
  244.   Tor with an "opt" until those versions of Tor are obsolete.  [Note that
  245.   key certificates, status vote documents, extra info documents, and
  246.   status consensus documents will never by read by older versions of Tor.]
  247.  
  248.   Other implementations that want to extend Tor's directory format MAY
  249.   introduce their own items.  The keywords for extension items SHOULD start
  250.   with the characters "x-" or "X-", to guarantee that they will not conflict
  251.   with keywords used by future versions of Tor.
  252.  
  253.   In our document descriptions below, we tag Items with a multiplicity in
  254.   brackets.  Possible tags are:
  255.  
  256.     "At start, exactly once": These items MUST occur in every instance of
  257.       the document type, and MUST appear exactly once, and MUST be the
  258.       first item in their documents.
  259.  
  260.     "Exactly once": These items MUST occur exactly one time in every
  261.       instance of the document type.
  262.  
  263.     "At end, exactly once": These items MUST occur in every instance of
  264.       the document type, and MUST appear exactly once, and MUST be the
  265.       last item in their documents.
  266.  
  267.     "At most once": These items MAY occur zero or one times in any
  268.       instance of the document type, but MUST NOT occur more than once.
  269.  
  270.     "Any number": These items MAY occur zero, one, or more times in any
  271.       instance of the document type.
  272.  
  273.     "Once or more": These items MUST occur at least once in any instance
  274.       of the document type, and MAY occur more.
  275.  
  276. 1.3. Signing documents
  277.  
  278.    Every signable document below is signed in a similar manner, using a
  279.    given "Initial Item", a final "Signature Item", a digest algorithm, and
  280.    a signing key.
  281.  
  282.    The Initial Item must be the first item in the document.
  283.  
  284.    The Signature Item has the following format:
  285.  
  286.      <signature item keyword> [arguments] NL SIGNATURE NL
  287.  
  288.    The "SIGNATURE" Object contains a signature (using the signing key) of
  289.    the PKCS1-padded digest of the entire document, taken from the
  290.    beginning of the Initial item, through the newline after the Signature
  291.    Item's keyword and its arguments.
  292.  
  293.    Unless otherwise, the digest algorithm is SHA-1.
  294.  
  295.    All documents are invalid unless signed with the correct signing key.
  296.  
  297.    The "Digest" of a document, unless stated otherwise, is its digest *as
  298.    signed by this signature scheme*.
  299.  
  300. 1.4. Voting timeline
  301.  
  302.    Every consensus document has a "valid-after" (VA) time, a "fresh-until"
  303.    (FU) time and a "valid-until" (VU) time.  VA MUST precede FU, which MUST
  304.    in turn precede VU.  Times are chosen so that every consensus will be
  305.    "fresh" until the next consensus becomes valid, and "valid" for a while
  306.    after.  At least 2 or 3 consensuses should be valid at any given time.
  307.  
  308.    The timeline for a given consensus is as follows:
  309.  
  310.    VA-DistSeconds-VoteSeconds: The authorities exchange votes.
  311.  
  312.    VA-DistSeconds: The authorities calculate the consensus and exchange
  313.    signatures.
  314.  
  315.    VA: All authorities have a multiply signed consensus.
  316.  
  317.    VA ... FU: Caches download the consensus.
  318.  
  319.    FU: The consensus is no long the freshest consensus.
  320.  
  321.    VU: The consensus is no longer valid.
  322.  
  323. 2. Router operation and formats
  324.  
  325.    ORs SHOULD generate a new router descriptor and a new extra-info
  326.    document whenever any of the following events have occurred:
  327.  
  328.       - A period of time (18 hrs by default) has passed since the last
  329.         time a descriptor was generated.
  330.  
  331.       - A descriptor field other than bandwidth or uptime has changed.
  332.  
  333.       - Bandwidth has changed by more than +/- 50% from the last time a
  334.         descriptor was generated, and at least a given interval of time
  335.         (20 mins by default) has passed since then.
  336.  
  337.       - Its uptime has been reset (by restarting).
  338.  
  339.    After generating a descriptor, ORs upload them to every directory
  340.    authority they know, by posting them (in order) to the URL
  341.  
  342.       http://<hostname:port>/tor/
  343.  
  344. 2.1. Router descriptor format
  345.  
  346.    Router descriptors consist of the following items.  For backward
  347.    compatibility, there should be an extra NL at the end of each router
  348.    descriptor.
  349.  
  350.    In lines that take multiple arguments, extra arguments SHOULD be
  351.    accepted and ignored.  Many of the nonterminals below are defined in
  352.    section 2.3.
  353.  
  354.      "router" nickname address ORPort SOCKSPort DirPort NL
  355.  
  356.        [At start, exactly once.]
  357.  
  358.        Indicates the beginning of a router descriptor.  "nickname" must be a
  359.        valid router nickname as specified in 2.3.  "address" must be an IPv4
  360.        address in dotted-quad format.  The last three numbers indicate the
  361.        TCP ports at which this OR exposes functionality. ORPort is a port at
  362.        which this OR accepts TLS connections for the main OR protocol;
  363.        SOCKSPort is deprecated and should always be 0; and DirPort is the
  364.        port at which this OR accepts directory-related HTTP connections.  If
  365.        any port is not supported, the value 0 is given instead of a port
  366.        number.  (At least one of DirPort and ORPort SHOULD be set;
  367.        authorities MAY reject any descriptor with both DirPort and ORPort of
  368.        0.)
  369.  
  370.     "bandwidth" bandwidth-avg bandwidth-burst bandwidth-observed NL
  371.  
  372.        [Exactly once]
  373.  
  374.        Estimated bandwidth for this router, in bytes per second.  The
  375.        "average" bandwidth is the volume per second that the OR is willing to
  376.        sustain over long periods; the "burst" bandwidth is the volume that
  377.        the OR is willing to sustain in very short intervals.  The "observed"
  378.        value is an estimate of the capacity this server can handle.  The
  379.        server remembers the max bandwidth sustained output over any ten
  380.        second period in the past day, and another sustained input.  The
  381.        "observed" value is the lesser of these two numbers.
  382.  
  383.     "platform" string NL
  384.  
  385.        [At most once]
  386.  
  387.        A human-readable string describing the system on which this OR is
  388.        running.  This MAY include the operating system, and SHOULD include
  389.        the name and version of the software implementing the Tor protocol.
  390.  
  391.     "published" YYYY-MM-DD HH:MM:SS NL
  392.  
  393.        [Exactly once]
  394.  
  395.        The time, in GMT, when this descriptor (and its corresponding
  396.        extra-info document if any)  was generated.
  397.  
  398.     "fingerprint" fingerprint NL
  399.  
  400.        [At most once]
  401.  
  402.        A fingerprint (a HASH_LEN-byte of asn1 encoded public key, encoded in
  403.        hex, with a single space after every 4 characters) for this router's
  404.        identity key. A descriptor is considered invalid (and MUST be
  405.        rejected) if the fingerprint line does not match the public key.
  406.  
  407.        [We didn't start parsing this line until Tor 0.1.0.6-rc; it should
  408.         be marked with "opt" until earlier versions of Tor are obsolete.]
  409.  
  410.     "hibernating" bool NL
  411.  
  412.        [At most once]
  413.  
  414.        If the value is 1, then the Tor server was hibernating when the
  415.        descriptor was published, and shouldn't be used to build circuits.
  416.  
  417.        [We didn't start parsing this line until Tor 0.1.0.6-rc; it should be
  418.         marked with "opt" until earlier versions of Tor are obsolete.]
  419.  
  420.     "uptime" number NL
  421.  
  422.        [At most once]
  423.  
  424.        The number of seconds that this OR process has been running.
  425.  
  426.     "onion-key" NL a public key in PEM format
  427.  
  428.        [Exactly once]
  429.  
  430.        This key is used to encrypt EXTEND cells for this OR.  The key MUST be
  431.        accepted for at least 1 week after any new key is published in a
  432.        subsequent descriptor. It MUST be 1024 bits.
  433.  
  434.     "signing-key" NL a public key in PEM format
  435.  
  436.        [Exactly once]
  437.  
  438.        The OR's long-term identity key.  It MUST be 1024 bits.
  439.  
  440.     "accept" exitpattern NL
  441.     "reject" exitpattern NL
  442.  
  443.        [Any number]
  444.  
  445.        These lines describe an "exit policy": the rules that an OR follows when
  446.        deciding whether to allow a new stream to a given address.  The
  447.        'exitpattern' syntax is described below.  The rules are considered in
  448.        order; if no rule matches, the address will be accepted.  For clarity,
  449.        the last such entry SHOULD be accept *:* or reject *:*.
  450.  
  451.     "router-signature" NL Signature NL
  452.  
  453.        [At end, exactly once]
  454.  
  455.        The "SIGNATURE" object contains a signature of the PKCS1-padded
  456.        hash of the entire router descriptor, taken from the beginning of the
  457.        "router" line, through the newline after the "router-signature" line.
  458.        The router descriptor is invalid unless the signature is performed
  459.        with the router's identity key.
  460.  
  461.     "contact" info NL
  462.  
  463.        [At most once]
  464.  
  465.        Describes a way to contact the server's administrator, preferably
  466.        including an email address and a PGP key fingerprint.
  467.  
  468.     "family" names NL
  469.  
  470.         [At most once]
  471.  
  472.         'Names' is a space-separated list of server nicknames or
  473.         hexdigests. If two ORs list one another in their "family" entries,
  474.         then OPs should treat them as a single OR for the purpose of path
  475.         selection.
  476.  
  477.         For example, if node A's descriptor contains "family B", and node B's
  478.         descriptor contains "family A", then node A and node B should never
  479.         be used on the same circuit.
  480.  
  481.     "read-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
  482.         [At most once]
  483.     "write-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
  484.         [At most once]
  485.  
  486.         Declare how much bandwidth the OR has used recently. Usage is divided
  487.         into intervals of NSEC seconds.  The YYYY-MM-DD HH:MM:SS field
  488.         defines the end of the most recent interval.  The numbers are the
  489.         number of bytes used in the most recent intervals, ordered from
  490.         oldest to newest.
  491.  
  492.         [We didn't start parsing these lines until Tor 0.1.0.6-rc; they should
  493.          be marked with "opt" until earlier versions of Tor are obsolete.]
  494.  
  495.         [See also migration notes in section 2.2.1.]
  496.  
  497.     "eventdns" bool NL
  498.  
  499.         [At most once]
  500.  
  501.         Declare whether this version of Tor is using the newer enhanced
  502.         dns logic.  Versions of Tor with this field set to false SHOULD NOT
  503.         be used for reverse hostname lookups.
  504.  
  505.         [All versions of Tor before 0.1.2.2-alpha should be assumed to have
  506.          this option set to 0 if it is not present.  All Tor versions at
  507.          0.1.2.2-alpha or later should be assumed to have this option set to
  508.          1 if it is not present.  Until 0.1.2.1-alpha-dev, this option was
  509.          not generated, even when the new DNS code was in use.  Versions of Tor
  510.          before 0.1.2.1-alpha-dev did not parse this option, so it should be
  511.          marked "opt".  The dnsworker logic has been removed, so this option
  512.          should not be used by new server code.  However, it can still be
  513.          used, and should still be recognized by new code until Tor 0.1.2.x
  514.          is obsolete.]
  515.  
  516.    "caches-extra-info" NL
  517.  
  518.        [At most once.]
  519.  
  520.        Present only if this router is a directory cache that provides
  521.        extra-info documents.
  522.  
  523.        [Versions before 0.2.0.1-alpha don't recognize this, and versions
  524.         before 0.1.2.5-alpha will reject descriptors containing it unless
  525.         it is prefixed with "opt"; it should be so prefixed until these
  526.         versions are obsolete.]
  527.  
  528.    "extra-info-digest" digest NL
  529.  
  530.        [At most once]
  531.  
  532.        "Digest" is a hex-encoded digest (using upper-case characters) of the
  533.        router's extra-info document, as signed in the router's extra-info
  534.        (that is, not including the signature).  (If this field is absent, the
  535.        router is not uploading a corresponding extra-info document.)
  536.  
  537.        [Versions before 0.2.0.1-alpha don't recognize this, and versions
  538.         before 0.1.2.5-alpha will reject descriptors containing it unless
  539.         it is prefixed with "opt"; it should be so prefixed until these
  540.         versions are obsolete.]
  541.  
  542. 2.2. Extra-info documents
  543.  
  544.    Extra-info documents consist of the following items:
  545.  
  546.     "extra-info" Nickname Fingerprint NL
  547.         [At start, exactly once.]
  548.  
  549.         Identifies what router this is an extra info descriptor for.
  550.         Fingerprint is encoded in hex (using upper-case letters), with
  551.         no spaces.
  552.  
  553.     "published"
  554.  
  555.        [Exactly once.]
  556.  
  557.        The time, in GMT, when this document (and its corresponding router
  558.        descriptor if any) was generated.  It MUST match the published time
  559.        in the corresponding router descriptor.
  560.  
  561.     "read-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
  562.         [At most once.]
  563.     "write-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
  564.         [At most once.]
  565.  
  566.         As documented in 2.1 above.  See migration notes in section 2.2.1.
  567.  
  568.     "router-signature" NL Signature NL
  569.         [At end, exactly once.]
  570.  
  571.         A document signature as documented in section 1.3, using the
  572.         initial item "extra-info" and the final item "router-signature",
  573.         signed with the router's identity key.
  574.  
  575. 2.2.1. Moving history fields to extra-info documents.
  576.  
  577.    Tools that want to use the read-history and write-history values SHOULD
  578.    download extra-info documents as well as router descriptors.  Such
  579.    tools SHOULD accept history values from both sources; if they appear in
  580.    both documents, the values in the extra-info documents are authoritative.
  581.  
  582.    At some future time, to save space, new versions of Tor will no longer
  583.    generate router descriptors containing read-history or write-history.
  584.    Tools should continue to accept read-history and write-history values
  585.    in router descriptors produced by older versions of Tor.
  586.  
  587. 2.3. Nonterminals in router descriptors
  588.  
  589.    nickname ::= between 1 and 19 alphanumeric characters, case-insensitive.
  590.    hexdigest ::= a '$', followed by 20 hexadecimal characters.
  591.       [Represents a server by the digest of its identity key.]
  592.  
  593.    exitpattern ::= addrspec ":" portspec
  594.    portspec ::= "*" | port | port "-" port
  595.    port ::= an integer between 1 and 65535, inclusive.
  596.  
  597.       [Some implementations incorrectly generate ports with value 0.
  598.        Implementations SHOULD accept this, and SHOULD NOT generate it.
  599.        Connections to port 0 are never permitted.]
  600.  
  601.    addrspec ::= "*" | ip4spec | ip6spec
  602.    ipv4spec ::= ip4 | ip4 "/" num_ip4_bits | ip4 "/" ip4mask
  603.    ip4 ::= an IPv4 address in dotted-quad format
  604.    ip4mask ::= an IPv4 mask in dotted-quad format
  605.    num_ip4_bits ::= an integer between 0 and 32
  606.    ip6spec ::= ip6 | ip6 "/" num_ip6_bits
  607.    ip6 ::= an IPv6 address, surrounded by square brackets.
  608.    num_ip6_bits ::= an integer between 0 and 128
  609.  
  610.    bool ::= "0" | "1"
  611.  
  612. 3. Formats produced by directory authorities.
  613.  
  614.    Every authority has two keys used in this protocol: a signing key, and
  615.    an authority identity key.  (Authorities also have a router identity
  616.    key used in their role as a router and by earlier versions of the
  617.    directory protocol.)  The identity key is used from time to time to
  618.    sign new key certificates using new signing keys; it is very sensitive.
  619.    The signing key is used to sign key certificates and status documents.
  620.  
  621.    There are three kinds of documents generated by directory authorities:
  622.  
  623.      Key certificates
  624.      Status votes
  625.      Status consensuses
  626.  
  627.    Each is discussed below.
  628.  
  629. 3.1. Key certificates
  630.  
  631.    Key certificates consist of the following items:
  632.  
  633.     "dir-key-certificate-version" version NL
  634.  
  635.         [At start, exactly once.]
  636.  
  637.         Determines the version of the key certificate.  MUST be "3" for
  638.         the protocol described in this document.  Implementations MUST
  639.         reject formats they don't understand.
  640.  
  641.     "fingerprint" fingerprint NL
  642.  
  643.         [Exactly once.]
  644.  
  645.         Hexadecimal encoding without spaces based on the authority's
  646.         identity key.
  647.  
  648.     "dir-identity-key" NL a public key in PEM format
  649.  
  650.         [Exactly once.]
  651.  
  652.         The long-term authority identity key for this authority.  This key
  653.         SHOULD be at least 2048 bits long; it MUST NOT be shorter than
  654.         1024 bits.
  655.  
  656.     "dir-key-published" YYYY-MM-DD HH:MM:SS NL
  657.  
  658.         [Exactly once.]
  659.  
  660.         The time (in GMT) when this document and corresponding key were
  661.         last generated.
  662.  
  663.     "dir-key-expires" YYYY-MM-DD HH:MM:SS NL
  664.  
  665.         [Exactly once.]
  666.  
  667.         A time (in GMT) after which this key is no longer valid.
  668.  
  669.     "dir-signing-key" NL a key in PEM format
  670.  
  671.         [Exactly once.]
  672.  
  673.         The directory server's public signing key.  This key MUST be at
  674.         least 1024 bits, and MAY be longer.
  675.  
  676.     "dir-key-certification" NL Signature NL
  677.  
  678.         [At end, exactly once.]
  679.  
  680.         A document signature as documented in section 1.3, using the
  681.         initial item "dir-key-certificate-version" and the final item
  682.         "dir-key-certification", signed with the authority identity key.
  683.  
  684.    Authorities MUST generate a new signing key and corresponding
  685.    certificate before the key expires.
  686.  
  687. 3.2. Vote and consensus status documents
  688.  
  689.    Votes and consensuses are more strictly formatted then other documents
  690.    in this specification, since different authorities must be able to
  691.    generate exactly the same consensus given the same set of votes.
  692.  
  693.    The procedure for deciding when to generate vote and consensus status
  694.    documents are described in section XXX below.
  695.  
  696.    Status documents contain a preamble, an authority section, a list of
  697.    router status entries, and one more footers signature, in that order.
  698.  
  699.    Unlike other formats described above, a SP in these documents must be a
  700.    single space character (hex 20).
  701.  
  702.    Some items appear only in votes, and some items appear only in
  703.    consensuses.  Unless specified, items occur in both.
  704.  
  705.    The preamble contains the following items.  They MUST occur in the
  706.    order given here:
  707.  
  708.     "network-status-version" SP version NL.
  709.  
  710.         [At start, exactly once.]
  711.  
  712.         A document format version.  For this specification, the version is
  713.         "3".
  714.  
  715.     "vote-status" SP type NL
  716.  
  717.         [Exactly once.]
  718.  
  719.         The status MUST be "vote" or "consensus", depending on the type of
  720.         the document.
  721.  
  722.     "consensus-methods" SP IntegerList NL
  723.  
  724.         [Exactly once for votes; does not occur in consensuses.]
  725.  
  726.         A space-separated list of supported methods for generating
  727.         consensuses from votes.  See section 3.4.1 for details.  Method "1"
  728.         MUST be included.
  729.  
  730.     "published" SP YYYY-MM-DD SP HH:MM:SS NL
  731.  
  732.         [Exactly once for votes; does not occur in consensuses.]
  733.  
  734.         The publication time for this status document (if a vote).
  735.  
  736.     "valid-after" SP YYYY-MM-DD SP HH:MM:SS NL
  737.  
  738.         [Exactly once.]
  739.  
  740.         The start of the Interval for this vote.  Before this time, the
  741.         consensus document produced from this vote should not be used.
  742.         See 1.4 for voting timeline information.
  743.  
  744.     "fresh-until" SP YYYY-MM-DD SP HH:MM:SS NL
  745.  
  746.         [Exactly once.]
  747.  
  748.         The time at which the next consensus should be produced; before this
  749.         time, there is no point in downloading another consensus, since there
  750.         won't be a new one.  See 1.4 for voting timeline information.
  751.  
  752.     "valid-until" SP YYYY-MM-DD SP HH:MM:SS NL
  753.  
  754.         [Exactly once.]
  755.  
  756.         The end of the Interval for this vote.  After this time, the
  757.         consensus produced by this vote should not be used.  See 1.4 for
  758.         voting timeline information.
  759.  
  760.     "voting-delay" SP VoteSeconds SP DistSeconds NL
  761.  
  762.         [Exactly once.]
  763.  
  764.         VoteSeconds is the number of seconds that we will allow to collect
  765.         votes from all authorities; DistSeconds is the number of seconds
  766.         we'll allow to collect signatures from all authorities. See 1.4 for
  767.         voting timeline information.
  768.  
  769.     "client-versions" SP VersionList NL
  770.  
  771.         [At most once.]
  772.  
  773.         A comma-separated list of recommended client versions, in
  774.         ascending order.  If absent, no opinion is held about client
  775.         versions.
  776.  
  777.     "server-versions" SP VersionList NL
  778.  
  779.         [At most once.]
  780.  
  781.         A comma-separated list of recommended server versions, in
  782.         ascending order.  If absent, no opinion is held about server
  783.         versions.
  784.  
  785.     "known-flags" SP FlagList NL
  786.  
  787.         [Exactly once.]
  788.  
  789.         A space-separated list of all of the flags that this document
  790.         might contain.  A flag is "known" either because the authority
  791.         knows about them and might set them (if in a vote), or because
  792.         enough votes were counted for the consensus for an authoritative
  793.         opinion to have been formed about their status.
  794.  
  795.  
  796.    The authority section of a vote contains the following items, followed
  797.    in turn by the authority's current key certificate:
  798.  
  799.     "dir-source" SP nickname SP identity SP address SP IP SP dirport SP
  800.        orport NL
  801.  
  802.         [Exactly once, at start]
  803.  
  804.         Describes this authority.  The nickname is a convenient identifier
  805.         for the authority.  The identity is an uppercase hex fingerprint of
  806.         the authority's current (v3 authority) identity key.  The address is
  807.         the server's hostname.  The IP is the server's current IP address,
  808.         and dirport is its current directory port. XXXXorport
  809.  
  810.     "contact" SP string NL
  811.  
  812.         [At most once.]
  813.  
  814.         An arbitrary string describing how to contact the directory
  815.         server's administrator.  Administrators should include at least an
  816.         email address and a PGP fingerprint.
  817.  
  818.    The authority section of a consensus contains groups the following items,
  819.    in the order given, with one group for each authority that contributed to
  820.    the consensus, with groups sorted by authority identity digest:
  821.  
  822.     "dir-source" SP nickname SP identity SP address SP IP SP dirport SP
  823.        orport NL
  824.  
  825.         [Exactly once, at start]
  826.  
  827.         As in the authority section of a vote.
  828.  
  829.     "contact" SP string NL
  830.  
  831.         [At most once.]
  832.  
  833.         As in the authority section of a vote.
  834.  
  835.     "vote-digest" SP digest NL
  836.  
  837.         [Exactly once.]
  838.  
  839.         A digest of the vote from the authority that contributed to this
  840.         consensus, as signed (that is, not including the signature).
  841.         (Hex, upper-case.)
  842.  
  843.    Each router status entry contains the following items.  Router status
  844.    entries are sorted in ascending order by identity digest.
  845.  
  846.     "r" SP nickname SP identity SP digest SP publication SP IP SP ORPort
  847.         SP DirPort NL
  848.  
  849.         [At start, exactly once.]
  850.  
  851.         "Nickname" is the OR's nickname.  "Identity" is a hash of its
  852.         identity key, encoded in base64, with trailing equals sign(s)
  853.         removed.  "Digest" is a hash of its most recent descriptor as
  854.         signed (that is, not including the signature), encoded in base64 as
  855.         "identity".  "Publication" is the
  856.         publication time of its most recent descriptor, in the form
  857.         YYYY-MM-DD HH:MM:SS, in GMT.  "IP" is its current IP address;
  858.         ORPort is its current OR port, "DirPort" is it's current directory
  859.         port, or "0" for "none".
  860.  
  861.     "s" SP Flags NL
  862.  
  863.         [At most once.]
  864.  
  865.         A series of space-separated status flags, in alphabetical order.
  866.         Currently documented flags are:
  867.  
  868.           "Authority" if the router is a directory authority.
  869.           "BadExit" if the router is believed to be useless as an exit node
  870.              (because its ISP censors it, because it is behind a restrictive
  871.              proxy, or for some similar reason).
  872.           "BadDirectory" if the router is believed to be useless as a
  873.              directory cache (because its directory port isn't working,
  874.              its bandwidth is always throttled, or for some similar
  875.              reason).
  876.           "Exit" if the router is useful for building general-purpose exit
  877.              circuits.
  878.           "Fast" if the router is suitable for high-bandwidth circuits.
  879.           "Guard" if the router is suitable for use as an entry guard.
  880.           "Named" if the router's identity-nickname mapping is canonical,
  881.              and this authority binds names.
  882.           "Stable" if the router is suitable for long-lived circuits.
  883.           "Running" if the router is currently usable.
  884.           "Valid" if the router has been 'validated'.
  885.           "V2Dir" if the router implements the v2 directory protocol.
  886.           "V3Dir" if the router implements this protocol.
  887.  
  888.     "v" SP version NL
  889.  
  890.         [At most once.]
  891.  
  892.         The version of the Tor protocol that this server is running.  If
  893.         the value begins with "Tor" SP, the rest of the string is a Tor
  894.         version number, and the protocol is "The Tor protocol as supported
  895.         by the given version of Tor."  Otherwise, if the value begins with
  896.         some other string, Tor has upgraded to a more sophisticated
  897.         protocol versioning system, and the protocol is "a version of the
  898.         Tor protocol more recent than any we recognize."
  899.  
  900.    The signature section contains the following item, which appears
  901.    Exactly Once for a vote, and At Least Once for a consensus.
  902.  
  903.     "directory-signature" SP identity SP signing-key-digest NL Signature
  904.  
  905.         This is a signature of the status document, with the initial item
  906.         "network-status-version", and the signature item
  907.         "directory-signature", using the signing key.  (In this case, we take
  908.         the hash through the _space_ after directory-signature, not the
  909.         newline: this ensures that all authorities sign the same thing.)
  910.         "identity" is the hex-encoded digest of the authority identity key of
  911.         the signing authority, and "signing-key-digest" is the hex-encoded
  912.         digest of the current authority signing key of the signing authority.
  913.  
  914. 3.3. Deciding how to vote.
  915.  
  916.    (This section describes how directory authorities choose which status
  917.    flags to apply to routers, as of Tor 0.2.0.0-alpha-dev. Later directory
  918.    authorities MAY do things differently, so long as clients keep working
  919.    well.  Clients MUST NOT depend on the exact behaviors in this section.)
  920.  
  921.    In the below definitions, a router is considered "active" if it is
  922.    running, valid, and not hibernating.
  923.  
  924.    "Valid" -- a router is 'Valid' if it is running a version of Tor not
  925.    known to be broken, and the directory authority has not blacklisted
  926.    it as suspicious.
  927.  
  928.    "Named" -- Directory authority administrators may decide to support name
  929.    binding.  If they do, then they must maintain a file of
  930.    nickname-to-identity-key mappings, and try to keep this file consistent
  931.    with other directory authorities.  If they don't, they act as clients, and
  932.    report bindings made by other directory authorities (name X is bound to
  933.    identity Y if at least one binding directory lists it, and no directory
  934.    binds X to some other Y'.)  A router is called 'Named' if the router
  935.    believes the given name should be bound to the given key.
  936.  
  937.    "Running" -- A router is 'Running' if the authority managed to connect to
  938.    it successfully within the last 30 minutes.
  939.  
  940.  
  941.    "Stable" -- A router is 'Stable' if it is active, and either its
  942.    Weighted MTBF is at least the median for known active routers or
  943.    its Weighted MTBF is at least 10 days. Routers are never called Stable if
  944.    they are running a version of Tor known to drop circuits stupidly.
  945.    (0.1.1.10-alpha through 0.1.1.16-rc are stupid this way.)
  946.  
  947.         To calculate weighted MTBF, compute the weighted mean of the lengths
  948.         of all intervals when the router was observed to be up, weighting
  949.         intervals by $\alpha^n$, where $n$ is the amount of time that has
  950.         passed since the interval ended, and $\alpha$ is chosen so that
  951.         measurements over approximately one month old no longer influence the
  952.         weighted MTBF much.
  953.  
  954.         [XXXX what happens when we have less than 4 days of MTBF info.]
  955.  
  956.    "Fast" -- A router is 'Fast' if it is active, and its bandwidth is
  957.    either in the top 7/8ths for known active routers or at least 100KB/s.
  958.  
  959.    "Guard" -- A router is a possible 'Guard' if it is 'Stable' and its
  960.    bandwidth is either at least the median for known active routers or
  961.    at least 250KB/s. If the total bandwidth of active non-BadExit Exit
  962.    servers is less than one third of the total bandwidth of all active
  963.    servers, no Exit is listed as a Guard.
  964.  
  965.    "Authority" -- A router is called an 'Authority' if the authority
  966.    generating the network-status document believes it is an authority.
  967.  
  968.    "V2Dir" -- A router supports the v2 directory protocol if it has an open
  969.    directory port, and it is running a version of the directory protocol that
  970.    supports the functionality clients need.  (Currently, this is
  971.    0.1.1.9-alpha or later.)
  972.  
  973.    "V3Dir" -- A router supports the v3 directory protocol if it has an open
  974.    directory port, and it is running a version of the directory protocol that
  975.    supports the functionality clients need.  (Currently, this is
  976.    0.2.0.?????-alpha or later.)
  977.  
  978.    Directory server administrators may label some servers or IPs as
  979.    blacklisted, and elect not to include them in their network-status lists.
  980.  
  981.    Authorities SHOULD 'disable' any servers in excess of 3 on any single IP.
  982.    When there are more than 3 to choose from, authorities should first prefer
  983.    authorities to non-authorities, then prefer Running to non-Running, and
  984.    then prefer high-bandwidth to low-bandwidth.  To 'disable' a server, the
  985.    authority *should* advertise it without the Running or Valid flag.
  986.  
  987.    Thus, the network-status vote includes all non-blacklisted,
  988.    non-expired, non-superseded descriptors.
  989.  
  990. 3.4. Computing a consensus from a set of votes
  991.  
  992.    Given a set of votes, authorities compute the contents of the consensus
  993.    document as follows:
  994.  
  995.      The "valid-after", "valid-until", and "fresh-until" times are taken as
  996.      the median of the respective values from all the votes.
  997.  
  998.      The times in the "voting-delay" line are taken as the median of the
  999.      VoteSeconds and DistSeconds times in the votes.
  1000.  
  1001.      Known-flags is the union of all flags known by any voter.
  1002.  
  1003.     "client-versions" and "server-versions" are sorted in ascending
  1004.      order; A version is recommended in the consensus if it is recommended
  1005.      by more than half of the voting authorities that included a
  1006.      client-versions or server-versions lines in their votes.
  1007.  
  1008.      The authority item groups (dir-source, contact, fignerprint,
  1009.      vote-digest) are taken from the votes of the voting
  1010.      authorities. These groups are sorted by the digests of the
  1011.      authorities identity keys, in ascending order.
  1012.  
  1013.      A router status entry:
  1014.         * is included in the result if some router status entry with the same
  1015.           identity is included by more than half of the authorities (total
  1016.           authorities, not just those whose votes we have).
  1017.  
  1018.         * For any given identity, we include at most one router status entry.
  1019.  
  1020.         * A router entry has a flag set if that is included by more than half
  1021.           of the authorities who care about that flag.
  1022.  
  1023.         * Two router entries are "the same" if they have the same
  1024.           <descriptor digest, published time, nickname, IP, ports> tuple.
  1025.           We choose the tuple for a given router as whichever tuple appears
  1026.           for that router in the most votes.  We break ties in favor of
  1027.           the more recently published.
  1028.  
  1029.         * The Named flag appears if it is included for this routerstatus by
  1030.           _any_ authority, and if all authorities that list it list the same
  1031.           nickname.
  1032.  
  1033.         * The version is given as whichever version is listed by the most
  1034.           voters, with ties decided in favor of more recent versions.
  1035.  
  1036.      The signatures at the end of a consensus document are sorted in
  1037.      ascending order by identity digest.
  1038.  
  1039. 3.4.1. Forward compatibility
  1040.  
  1041.    Future versions of Tor will need to include new information in the
  1042.    consensus documents, but it is important that all authorities (or at least
  1043.    half) generate and sign the same signed consensus.
  1044.  
  1045.    To achieve this, authorities list in their votes their supported methods
  1046.    for generating consensuses from votes.  The method described above and
  1047.    implemented in Tor 0.2.0.x is "1".  Later methods will be assigned higher
  1048.    numbers.
  1049.  
  1050.    Before generating a consensus, an authority must decide which consensus
  1051.    method to use.  To do this, it looks for the highest version number
  1052.    supported by more than 2/3 of the authorities.  If it supports this
  1053.    method, then it uses it.  Otherwise, it falls back to method 1.
  1054.  
  1055. 3.5. Detached signatures
  1056.  
  1057.    Assuming full connectivity, every authority should compute and sign the
  1058.    same consensus directory in each period.  Therefore, it isn't necessary to
  1059.    download the consensus computed by each authority; instead, the
  1060.    authorities only push/fetch each others' signatures.  A "detached
  1061.    signature" document contains items as follows:
  1062.  
  1063.     "consensus-digest" SP Digest NL
  1064.  
  1065.         [At start, at most once.]
  1066.  
  1067.         The digest of the consensus being signed.
  1068.  
  1069.     "valid-after" SP YYYY-MM-DD SP HH:MM:SS NL
  1070.     "fresh-until" SP YYYY-MM-DD SP HH:MM:SS NL
  1071.     "valid-until" SP YYYY-MM-DD SP HH:MM:SS NL
  1072.  
  1073.         [As in the consensus]
  1074.  
  1075.     "directory-signature"
  1076.  
  1077.         [As in the consensus; the signature object is the same as in the
  1078.         consensus document.]
  1079.  
  1080.  
  1081. 4. Directory server operation
  1082.  
  1083.    All directory authorities and directory caches ("directory servers")
  1084.    implement this section, except as noted.
  1085.  
  1086. 4.1. Accepting uploads (authorities only)
  1087.  
  1088.    When a router posts a signed descriptor to a directory authority, the
  1089.    authority first checks whether it is well-formed and correctly
  1090.    self-signed.  If it is, the authority next verifies that the nickname
  1091.    question is already assigned to a router with a different public key.
  1092.    Finally, the authority MAY check that the router is not blacklisted
  1093.    because of its key, IP, or another reason.
  1094.  
  1095.    If the descriptor passes these tests, and the authority does not already
  1096.    have a descriptor for a router with this public key, it accepts the
  1097.    descriptor and remembers it.
  1098.  
  1099.    If the authority _does_ have a descriptor with the same public key, the
  1100.    newly uploaded descriptor is remembered if its publication time is more
  1101.    recent than the most recent old descriptor for that router, and either:
  1102.       - There are non-cosmetic differences between the old descriptor and the
  1103.         new one.
  1104.       - Enough time has passed between the descriptors' publication times.
  1105.         (Currently, 12 hours.)
  1106.  
  1107.    Differences between router descriptors are "non-cosmetic" if they would be
  1108.    sufficient to force an upload as described in section 2 above.
  1109.  
  1110.    Note that the "cosmetic difference" test only applies to uploaded
  1111.    descriptors, not to descriptors that the authority downloads from other
  1112.    authorities.
  1113.  
  1114.    When a router posts a signed extra-info document to a directory authority,
  1115.    the authority again checks it for well-formedness and correct signature,
  1116.    and checks that its matches the extra-info-digest in some router
  1117.    descriptor that it believes is currently useful.  If so, it accepts it and
  1118.    stores it and serves it as requested.  If not, it drops it.
  1119.  
  1120. 4.2. Voting (authorities only)
  1121.  
  1122.    Authorities divide time into Intervals.  Authority administrators SHOULD
  1123.    try to all pick the same interval length, and SHOULD pick intervals that
  1124.    are commonly used divisions of time (e.g., 5 minutes, 15 minutes, 30
  1125.    minutes, 60 minutes, 90 minutes).  Voting intervals SHOULD be chosen to
  1126.    divide evenly into a 24-hour day.
  1127.  
  1128.    Authorities SHOULD act according to interval and delays in the
  1129.    latest consensus.  Lacking a latest consensus, they SHOULD default to a
  1130.    30-minute Interval, a 5 minute VotingDelay, and a 5 minute DistDelay.
  1131.  
  1132.    Authorities MUST take pains to ensure that their clocks remain accurate
  1133.    within a few seconds.  (Running NTP is usually sufficient.)
  1134.  
  1135.    The first voting period of each day begins at 00:00 (midnight) GMT.  If
  1136.    the last period of the day would be truncated by one-half or more, it is
  1137.    merged with the second-to-last period.
  1138.  
  1139.    An authority SHOULD publish its vote immediately at the start of each voting
  1140.    period (minus VoteSeconds+DistSeconds).  It does this by making it
  1141.    available at
  1142.      http://<hostname>/tor/status-vote/next/authority.z
  1143.    and sending it in an HTTP POST request to each other authority at the URL
  1144.      http://<hostname>/tor/post/vote
  1145.  
  1146.    If, at the start of the voting period, minus DistSeconds, an authority
  1147.    does not have a current statement from another authority, the first
  1148.    authority downloads the other's statement.
  1149.  
  1150.    Once an authority has a vote from another authority, it makes it available
  1151.    at
  1152.       http://<hostname>/tor/status-vote/next/<fp>.z
  1153.    where <fp> is the fingerprint of the other authority's identity key.
  1154.  
  1155.    The consensus status, along with as many signatures as the server
  1156.    currently knows, should be available at
  1157.       http://<hostname>/tor/status-vote/next/consensus.z
  1158.    All of the detached signatures it knows for consensus status should be
  1159.    available at:
  1160.       http://<hostname>/tor/status-vote/next/consensus-signatures.z
  1161.  
  1162.    Once there are enough signatures, or once the voting period starts,
  1163.    these documents are available at
  1164.       http://<hostname>/tor/status-vote/current/consensus.z
  1165.    and
  1166.       http://<hostname>/tor/status-vote/current/consensus-signatures.z
  1167.  
  1168.    Once an authority has computed and signed a consensus network status, it
  1169.    should send its detached signature to each other authority in an HTTP POST
  1170.    request to the URL:
  1171.       http://<hostname>/tor/post/consensus-signature
  1172.  
  1173.    [XXX Note why we support push-and-then-pull.]
  1174.  
  1175.    [XXX possible future features include support for downloading old
  1176.     consensuses.]
  1177.  
  1178. 4.3. Downloading consensus status documents (caches only)
  1179.  
  1180.    All directory servers (authorities and caches) try to keep a recent
  1181.    network-status consensus document to serve to clients.  A cache ALWAYS
  1182.    downloads a network-status consensus if any of the following are true:
  1183.      - The cache has no consensus document.
  1184.      - The cache's consensus document is no longer valid.
  1185.    Otherwise, the cache downloads a new consensus document at a randomly
  1186.    chosen time after its current consensus stops being fresh.  (This time is
  1187.    chosen at random to avoid swarming the authorities at the start of each
  1188.    period.)
  1189.  
  1190. 4.4. Downloading and storing router descriptors (authorities and caches)
  1191.  
  1192.    Periodically (currently, every 10 seconds), directory servers check
  1193.    whether there are any specific descriptors that they do not have and that
  1194.    they are not currently trying to download.  Caches identify these
  1195.    descriptors by hash in the recent network-status consensus documents;
  1196.    authorities identify them by hash in vote (if publication date is more
  1197.    recent than the descriptor we currently have).
  1198.  
  1199.  [XXXX need a way to fetch descriptors ahead of the vote?  v2 status docs can
  1200.  do that for now.]
  1201.  
  1202.    If so, the directory server launches requests to the authorities for these
  1203.    descriptors, such that each authority is only asked for descriptors listed
  1204.    in its most recent vote (if the requester is an authority) or in the
  1205.    consensus (if the requester is a cache).  If we're an authority, and more
  1206.    than one authority lists the descriptor, we choose which to ask at random.
  1207.  
  1208.    If one of these downloads fails, we do not try to download that descriptor
  1209.    from the authority that failed to serve it again unless we receive a newer
  1210.    network-status (consensus or vote) from that authority that lists the same
  1211.    descriptor.
  1212.  
  1213.    Directory servers must potentially cache multiple descriptors for each
  1214.    router. Servers must not discard any descriptor listed by any recent
  1215.    consensus.  If there is enough space to store additional descriptors,
  1216.    servers SHOULD try to hold those which clients are likely to download the
  1217.    most.  (Currently, this is judged based on the interval for which each
  1218.    descriptor seemed newest.)
  1219. [XXXX define recent]
  1220.  
  1221.    Authorities SHOULD NOT download descriptors for routers that they would
  1222.    immediately reject for reasons listed in 3.1.
  1223.  
  1224. 4.5. Downloading and storing extra-info documents
  1225.  
  1226.    All authorities, and any cache that chooses to cache extra-info documents,
  1227.    and any client that uses extra-info documents, should implement this
  1228.    section.
  1229.  
  1230.    Note that generally, clients don't need extra-info documents.
  1231.  
  1232.    Periodically, the Tor instance checks whether it is missing any extra-info
  1233.    documents: in other words, if it has any router descriptors with an
  1234.    extra-info-digest field that does not match any of the extra-info
  1235.    documents currently held.  If so, it downloads whatever extra-info
  1236.    documents are missing.  Caches download from authorities; non-caches try
  1237.    to download from caches.  We follow the same splitting and back-off rules
  1238.    as in 4.4 (if a cache) or 5.3 (if a client).
  1239.  
  1240. 4.6. General-use HTTP URLs
  1241.  
  1242.    "Fingerprints" in these URLs are base-16-encoded SHA1 hashes.
  1243.  
  1244.    The most recent v3 consensus should be available at:
  1245.       http://<hostname>/tor/status-vote/current/consensus.z
  1246.  
  1247.    A concatenated set of all the current key certificates should be available
  1248.    at:
  1249.       http://<hostname>/tor/keys/all.z
  1250.  
  1251.    The key certificate for this server (if it is an authority) should be
  1252.    available at:
  1253.       http://<hostname>/tor/keys/authority.z
  1254.  
  1255.    The key certificate for an authority whose authority identity fingerprint
  1256.    is <F> should be available at:
  1257.       http://<hostname>/tor/keys/fp/<F>.z
  1258.  
  1259.    The key certificate whose signing key is <F> should be available at:
  1260.       http://<hostname>/tor/keys/fp/<F>.z
  1261.    [XXX020 cross-certify?]
  1262.  
  1263.    The most recent descriptor for a server whose identity key has a
  1264.    fingerprint of <F> should be available at:
  1265.       http://<hostname>/tor/server/fp/<F>.z
  1266.  
  1267.    The most recent descriptors for servers with identity fingerprints
  1268.    <F1>,<F2>,<F3> should be available at:
  1269.       http://<hostname>/tor/server/fp/<F1>+<F2>+<F3>.z
  1270.  
  1271.    (NOTE: Implementations SHOULD NOT download descriptors by identity key
  1272.    fingerprint. This allows a corrupted server (in collusion with a cache) to
  1273.    provide a unique descriptor to a client, and thereby partition that client
  1274.    from the rest of the network.)
  1275.  
  1276.    The server descriptor with (descriptor) digest <D> (in hex) should be
  1277.    available at:
  1278.       http://<hostname>/tor/server/d/<D>.z
  1279.  
  1280.    The most recent descriptors with digests <D1>,<D2>,<D3> should be
  1281.    available at:
  1282.       http://<hostname>/tor/server/d/<D1>+<D2>+<D3>.z
  1283.  
  1284.    The most recent descriptor for this server should be at:
  1285.       http://<hostname>/tor/server/authority.z
  1286.     [Nothing in the Tor protocol uses this resource yet, but it is useful
  1287.      for debugging purposes. Also, the official Tor implementations
  1288.      (starting at 0.1.1.x) use this resource to test whether a server's
  1289.      own DirPort is reachable.]
  1290.  
  1291.    A concatenated set of the most recent descriptors for all known servers
  1292.    should be available at:
  1293.       http://<hostname>/tor/server/all.z
  1294.  
  1295.    Extra-info documents are available at the URLS
  1296.       http://<hostname>/tor/extra/d/...
  1297.       http://<hostname>/tor/extra/fp/...
  1298.       http://<hostname>/tor/extra/all[.z]
  1299.       http://<hostname>/tor/extra/authority[.z]
  1300.          (As for /tor/server/ URLs: supports fetching extra-info
  1301.          documents by their digest, by the fingerprint of their servers,
  1302.          or all at once. When serving by fingerprint, we serve the
  1303.          extra-info that corresponds to the descriptor we would serve by
  1304.          that fingerprint. Only directory authorities of version
  1305.          0.2.0.1-alpha or later are guaranteed to support the first
  1306.          three classes of URLs.  Caches may support them, and MUST
  1307.          support them if they have advertised "caches-extra-info".)
  1308.  
  1309.    For debugging, directories SHOULD expose non-compressed objects at URLs like
  1310.    the above, but without the final ".z".
  1311.    Clients MUST handle compressed concatenated information in two forms:
  1312.      - A concatenated list of zlib-compressed objects.
  1313.      - A zlib-compressed concatenated list of objects.
  1314.    Directory servers MAY generate either format: the former requires less
  1315.    CPU, but the latter requires less bandwidth.
  1316.  
  1317.    Clients SHOULD use upper case letters (A-F) when base16-encoding
  1318.    fingerprints.  Servers MUST accept both upper and lower case fingerprints
  1319.    in requests.
  1320.  
  1321. 5. Client operation: downloading information
  1322.  
  1323.    Every Tor that is not a directory server (that is, those that do
  1324.    not have a DirPort set) implements this section.
  1325.  
  1326. 5.1. Downloading network-status documents
  1327.  
  1328.    Each client maintains a list of directory authorities.  Insofar as
  1329.    possible, clients SHOULD all use the same list.
  1330.  
  1331.    Clients try to have a live consensus network-status document at all times.
  1332.    A network-status document is "live" if the time in its valid-until field
  1333.    has not passed.
  1334.  
  1335.    If a client is missing a live network-status document, it tries to fetch
  1336.    it from a directory cache (or from an authority if it knows no caches).
  1337.    On failure, the client waits briefly, then tries that network-status
  1338.    document again from another cache.  The client does not build circuits
  1339.    until it has a live network-status consensus document, and it has
  1340.    descriptors for more than 1/4 of the routers that it believes are running.
  1341.  
  1342.    (Note: clients can and should pick caches based on the network-status
  1343.    information they have: once they have first fetched network-status info
  1344.    from an authority, they should not need to go to the authority directly
  1345.    again.)
  1346.  
  1347.  
  1348. 5.2. Downloading and storing router descriptors
  1349.  
  1350.    Clients try to have the best descriptor for each router.  A descriptor is
  1351.    "best" if:
  1352.       * It is listed in the consensus network-status document.
  1353.  
  1354.    Periodically (currently every 10 seconds) clients check whether there are
  1355.    any "downloadable" descriptors.  A descriptor is downloadable if:
  1356.       - It is the "best" descriptor for some router.
  1357.       - The descriptor was published at least 10 minutes in the past.
  1358.         (This prevents clients from trying to fetch descriptors that the
  1359.         mirrors have probably not yet retrieved and cached.)
  1360.       - The client does not currently have it.
  1361.       - The client is not currently trying to download it.
  1362.       - The client would not discard it immediately upon receiving it.
  1363.       - The client thinks it is running and valid (see 6.1 below).
  1364.  
  1365.    If at least 16 known routers have downloadable descriptors, or if
  1366.    enough time (currently 10 minutes) has passed since the last time the
  1367.    client tried to download descriptors, it launches requests for all
  1368.    downloadable descriptors, as described in 5.3 below.
  1369.  
  1370.    When a descriptor download fails, the client notes it, and does not
  1371.    consider the descriptor downloadable again until a certain amount of time
  1372.    has passed. (Currently 0 seconds for the first failure, 60 seconds for the
  1373.    second, 5 minutes for the third, 10 minutes for the fourth, and 1 day
  1374.    thereafter.)  Periodically (currently once an hour) clients reset the
  1375.    failure count.
  1376.  
  1377.    Clients retain the most recent descriptor they have downloaded for each
  1378.    router so long as it is not too old (currently, 48 hours), OR so long as
  1379.    no better descriptor has been downloaded for the same router.
  1380.  
  1381.    [Versions of Tor before 0.1.2.3-alpha would discard descriptors simply for
  1382.    being published too far in the past.]  [The code seems to discard
  1383.    descriptors in all cases after they're 5 days old. True? -RD]
  1384.  
  1385. 5.3. Managing downloads
  1386.  
  1387.    When a client has no consensus network-status document, it downloads it
  1388.    from a randomly chosen authority.  In all other cases, the client
  1389.    downloads from caches randomly chosen from among those believed to be V2
  1390.    directory servers.  (This information comes from the network-status
  1391.    documents; see 6 below.)
  1392.  
  1393.    When downloading multiple router descriptors, the client chooses multiple
  1394.    mirrors so that:
  1395.      - At least 3 different mirrors are used, except when this would result
  1396.        in more than one request for under 4 descriptors.
  1397.      - No more than 128 descriptors are requested from a single mirror.
  1398.      - Otherwise, as few mirrors as possible are used.
  1399.    After choosing mirrors, the client divides the descriptors among them
  1400.    randomly.
  1401.  
  1402.    After receiving any response client MUST discard any network-status
  1403.    documents and descriptors that it did not request.
  1404.  
  1405. 6. Using directory information
  1406.  
  1407.    Everyone besides directory authorities uses the approaches in this section
  1408.    to decide which servers to use and what their keys are likely to be.
  1409.    (Directory authorities just believe their own opinions, as in 3.1 above.)
  1410.  
  1411. 6.1. Choosing routers for circuits.
  1412.  
  1413.    Circuits SHOULD NOT be built until the client has enough directory
  1414.    information: a live consensus network status [XXXX fallback?]  and
  1415.    descriptors for at least 1/4 of the servers believed to be running.
  1416.  
  1417.    A server is "listed" if it is included by the consensus network-status
  1418.    document.  Clients SHOULD NOT use unlisted servers.
  1419.  
  1420.    These flags are used as follows:
  1421.  
  1422.      - Clients SHOULD NOT use non-'Valid' or non-'Running' routers unless
  1423.        requested to do so.
  1424.  
  1425.      - Clients SHOULD NOT use non-'Fast' routers for any purpose other than
  1426.        very-low-bandwidth circuits (such as introduction circuits).
  1427.  
  1428.      - Clients SHOULD NOT use non-'Stable' routers for circuits that are
  1429.        likely to need to be open for a very long time (such as those used for
  1430.        IRC or SSH connections).
  1431.  
  1432.      - Clients SHOULD NOT choose non-'Guard' nodes when picking entry guard
  1433.        nodes.
  1434.  
  1435.      - Clients SHOULD NOT download directory information from non-'V2Dir'
  1436.        caches.
  1437.  
  1438. 6.2. Managing naming
  1439.  
  1440.    [XXXX rewrite for v3]
  1441.  
  1442.    In order to provide human-memorable names for individual server
  1443.    identities, some directory servers bind names to IDs.  Clients handle
  1444.    names in two ways:
  1445.  
  1446.    When a client encounters a name it has not mapped before:
  1447.  
  1448.       If all the live "Naming" network-status documents the client has
  1449.       claim that the name binds to some identity ID, and the client has at
  1450.       least three live network-status documents, the client maps the name to
  1451.       ID.
  1452.  
  1453.    When a user tries to refer to a router with a name that does not have a
  1454.    mapping under the above rules, the implementation SHOULD warn the user.
  1455.    After giving the warning, the implementation MAY use a router that at
  1456.    least one Naming authority maps the name to, so long as no other naming
  1457.    authority maps that name to a different router.  If no Naming authority
  1458.    maps the name to a router, the implementation MAY use any router that
  1459.    advertises the name.
  1460.  
  1461.    Not every router needs a nickname.  When a router doesn't configure a
  1462.    nickname, it publishes with the default nickname "Unnamed".  Authorities
  1463.    SHOULD NOT ever mark a router with this nickname as Named; client software
  1464.    SHOULD NOT ever use a router in response to a user request for a router
  1465.    called "Unnamed".
  1466.  
  1467. 6.3. Software versions
  1468.  
  1469.    An implementation of Tor SHOULD warn when it has fetched a consensus
  1470.    network-status, and it is running a software version not listed.
  1471.  
  1472. 6.4. Warning about a router's status.
  1473.  
  1474.    If a router tries to publish its descriptor to a Naming authority
  1475.    that has its nickname mapped to another key, the router SHOULD
  1476.    warn the operator that it is either using the wrong key or is using
  1477.    an already claimed nickname.
  1478.  
  1479.    If a router has fetched a consensus document,, and the
  1480.    authorities do not publish a binding for the router's nickname, the
  1481.    router MAY remind the operator that the chosen nickname is not
  1482.    bound to this key at the authorities, and suggest contacting the
  1483.    authority operators.
  1484.  
  1485.    ...
  1486.  
  1487. 6.5. Router protocol versions
  1488.  
  1489.    A client should believe that a router supports a given feature if that
  1490.    feature is supported by the router or protocol versions in more than half
  1491.    of the live networkstatus's "v" entries for that router.  In other words,
  1492.    if the "v" entries for some router are:
  1493.        v Tor 0.0.8pre1                (from authority 1)
  1494.        v Tor 0.1.2.11                 (from authority 2)
  1495.        v FutureProtocolDescription 99 (from authority 3)
  1496.    then the client should believe that the router supports any feature
  1497.    supported by 0.1.2.11.
  1498.  
  1499.    This is currently equivalent to believing the median declared version for
  1500.    a router in all live networkstatuses.
  1501.  
  1502. 7. Standards compliance
  1503.  
  1504.    All clients and servers MUST support HTTP 1.0.  Clients and servers MAY
  1505.    support later versions of HTTP as well.
  1506.  
  1507. 7.1. HTTP headers
  1508.  
  1509.   Servers MAY set the Content-Length: header.  Servers SHOULD set
  1510.   Content-Encoding to "deflate" or "identity".
  1511.  
  1512.   Servers MAY include an X-Your-Address-Is: header, whose value is the
  1513.   apparent IP address of the client connecting to them (as a dotted quad).
  1514.   For directory connections tunneled over a BEGIN_DIR stream, servers SHOULD
  1515.   report the IP from which the circuit carrying the BEGIN_DIR stream reached
  1516.   them.  [Servers before version 0.1.2.5-alpha reported 127.0.0.1 for all
  1517.   BEGIN_DIR-tunneled connections.]
  1518.  
  1519.   Servers SHOULD disable caching of multiple network statuses or multiple
  1520.   router descriptors.  Servers MAY enable caching of single descriptors,
  1521.   single network statuses, the list of all router descriptors, a v1
  1522.   directory, or a v1 running routers document.  XXX mention times.
  1523.  
  1524. 7.2. HTTP status codes
  1525.  
  1526.   Tor delivers the following status codes.  Some were chosen without much
  1527.   thought; other code SHOULD NOT rely on specific status codes yet.
  1528.  
  1529.   200 -- the operation completed successfully
  1530.       -- the user requested statuses or serverdescs, and none of the ones we
  1531.          requested were found (0.2.0.4-alpha and earlier).
  1532.  
  1533.   304 -- the client specified an if-modified-since time, and none of the
  1534.          requested resources have changed since that time.
  1535.  
  1536.   400 -- the request is malformed, or
  1537.       -- the URL is for a malformed variation of one of the URLs we support,
  1538.           or
  1539.       -- the client tried to post to a non-authority, or
  1540.       -- the authority rejected a malformed posted document, or
  1541.  
  1542.   404 -- the requested document was not found.
  1543.       -- the user requested statuses or serverdescs, and none of the ones we
  1544.          requested were found (0.2.0.5-alpha and later).
  1545.  
  1546.   503 -- we are declining the request in order to save bandwidth
  1547.       -- user requested some items that we ordinarily generate or store,
  1548.          but we do not have any available.
  1549.  
  1550. 9. Backward compatibility and migration plans
  1551.  
  1552.   Until Tor versions before 0.1.1.x are completely obsolete, directory
  1553.   authorities should generate, and mirrors should download and cache, v1
  1554.   directories and running-routers lists, and allow old clients to download
  1555.   them.  These documents and the rules for retrieving, serving, and caching
  1556.   them are described in dir-spec-v1.txt.
  1557.  
  1558.   Until Tor versions before 0.2.0.x are completely obsolete, directory
  1559.   authorities should generate, mirrors should download and cache, v2
  1560.   network-status documents, and allow old clients to download them.
  1561.   Additionally, all directory servers and caches should download, store, and
  1562.   serve any router descriptor that is required because of v2 network-status
  1563.   documents. These documents and the rules for retrieving, serving, and
  1564.   caching them are described in dir-spec-v1.txt.
  1565.  
  1566. A. Consensus-negotiation timeline.
  1567.  
  1568.  
  1569.    Period begins: this is the Published time.
  1570.      Everybody sends votes
  1571.    Reconciliation: everybody tries to fetch missing votes.
  1572.      consensus may exist at this point.
  1573.    End of voting period:
  1574.      everyone swaps signatures.
  1575.    Now it's okay for caches to download
  1576.      Now it's okay for clients to download.
  1577.  
  1578.    Valid-after/valid-until switchover
  1579.  
  1580.